<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>xilpuf: XilPuf Server APIs</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="HTML_custom.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="xlogo_bg.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">xilpuf
   </div>
   <div id="projectbrief">Vitis Drivers API Documentation</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Overview</span></a></li>
      <li><a href="globals.html"><span>APIs</span></a></li>
      <li><a href="files.html"><span>File&#160;List</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;"
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('group__xpuf__server__apis.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="summary">
<a href="#define-members">Macros</a> &#124;
<a href="#func-members">Functions</a>  </div>
  <div class="headertitle">
<div class="title">XilPuf Server APIs</div>  </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:ga8eda4f7307742eae0ea34465e43d2555"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__xpuf__server__apis.html#ga8eda4f7307742eae0ea34465e43d2555">XPUF_STATUS_WAIT_TIMEOUT</a>&#160;&#160;&#160;(1000000U)</td></tr>
<tr class="memdesc:ga8eda4f7307742eae0ea34465e43d2555"><td class="mdescLeft">&#160;</td><td class="mdescRight">Recommended software timeout is 1 second.  <a href="#ga8eda4f7307742eae0ea34465e43d2555">More...</a><br/></td></tr>
<tr class="separator:ga8eda4f7307742eae0ea34465e43d2555"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga4d7d5a3b73fb92f6f65e2a2205b74195"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__xpuf__server__apis.html#ga4d7d5a3b73fb92f6f65e2a2205b74195">XPUF_AUX_MASK_VALUE</a>&#160;&#160;&#160;(0x0FFFFFF0U)</td></tr>
<tr class="memdesc:ga4d7d5a3b73fb92f6f65e2a2205b74195"><td class="mdescLeft">&#160;</td><td class="mdescRight">Mask value for AUX.  <a href="#ga4d7d5a3b73fb92f6f65e2a2205b74195">More...</a><br/></td></tr>
<tr class="separator:ga4d7d5a3b73fb92f6f65e2a2205b74195"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga4ab1beae9987b6ab994e4cf06c77dc1a"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__xpuf__server__apis.html#ga4ab1beae9987b6ab994e4cf06c77dc1a">XPUF_AUX_SHIFT_VALUE</a>&#160;&#160;&#160;(4U)</td></tr>
<tr class="memdesc:ga4ab1beae9987b6ab994e4cf06c77dc1a"><td class="mdescLeft">&#160;</td><td class="mdescRight">No of bits aux has to shift.  <a href="#ga4ab1beae9987b6ab994e4cf06c77dc1a">More...</a><br/></td></tr>
<tr class="separator:ga4ab1beae9987b6ab994e4cf06c77dc1a"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:gae2607f20a8f0199c8f0eb53d0dfc9f0a"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__xpuf__server__apis.html#gae2607f20a8f0199c8f0eb53d0dfc9f0a">XPuf_Registration</a> (XPuf_Data *PufData)</td></tr>
<tr class="memdesc:gae2607f20a8f0199c8f0eb53d0dfc9f0a"><td class="mdescLeft">&#160;</td><td class="mdescRight">This functions performs PUF registration.  <a href="#gae2607f20a8f0199c8f0eb53d0dfc9f0a">More...</a><br/></td></tr>
<tr class="separator:gae2607f20a8f0199c8f0eb53d0dfc9f0a"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga2f60c4624b046d3f5c74d8cb01f8f90d"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__xpuf__server__apis.html#ga2f60c4624b046d3f5c74d8cb01f8f90d">XPuf_Regeneration</a> (XPuf_Data *PufData)</td></tr>
<tr class="memdesc:ga2f60c4624b046d3f5c74d8cb01f8f90d"><td class="mdescLeft">&#160;</td><td class="mdescRight">This function regenerates PUF data using helper data stored in eFUSE or external memory.  <a href="#ga2f60c4624b046d3f5c74d8cb01f8f90d">More...</a><br/></td></tr>
<tr class="separator:ga2f60c4624b046d3f5c74d8cb01f8f90d"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga651bbcfe2834f71fa821e1cb113a723f"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__xpuf__server__apis.html#ga651bbcfe2834f71fa821e1cb113a723f">XPuf_ClearPufID</a> (void)</td></tr>
<tr class="memdesc:ga651bbcfe2834f71fa821e1cb113a723f"><td class="mdescLeft">&#160;</td><td class="mdescRight">This function clears PUF ID.  <a href="#ga651bbcfe2834f71fa821e1cb113a723f">More...</a><br/></td></tr>
<tr class="separator:ga651bbcfe2834f71fa821e1cb113a723f"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga03c85715b04394967ebb2274f09f510a"><td class="memItemLeft" align="right" valign="top">int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__xpuf__server__apis.html#ga03c85715b04394967ebb2274f09f510a">XPuf_GenerateFuseFormat</a> (XPuf_Data *PufData)</td></tr>
<tr class="memdesc:ga03c85715b04394967ebb2274f09f510a"><td class="mdescLeft">&#160;</td><td class="mdescRight">Converts the PUF Syndrome data to eFUSE writing format.  <a href="#ga03c85715b04394967ebb2274f09f510a">More...</a><br/></td></tr>
<tr class="separator:ga03c85715b04394967ebb2274f09f510a"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<h2 class="groupheader">Macro Definition Documentation</h2>
<a class="anchor" id="ga4d7d5a3b73fb92f6f65e2a2205b74195"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">#define XPUF_AUX_MASK_VALUE&#160;&#160;&#160;(0x0FFFFFF0U)</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Mask value for AUX. </p>

<p>Referenced by <a class="el" href="group__xpuf__server__apis.html#gae2607f20a8f0199c8f0eb53d0dfc9f0a">XPuf_Registration()</a>.</p>

</div>
</div>
<a class="anchor" id="ga4ab1beae9987b6ab994e4cf06c77dc1a"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">#define XPUF_AUX_SHIFT_VALUE&#160;&#160;&#160;(4U)</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>No of bits aux has to shift. </p>

<p>Referenced by <a class="el" href="group__xpuf__server__apis.html#gae2607f20a8f0199c8f0eb53d0dfc9f0a">XPuf_Registration()</a>.</p>

</div>
</div>
<a class="anchor" id="ga8eda4f7307742eae0ea34465e43d2555"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">#define XPUF_STATUS_WAIT_TIMEOUT&#160;&#160;&#160;(1000000U)</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Recommended software timeout is 1 second. </p>

<p>Referenced by <a class="el" href="group__xpuf__server__apis.html#ga651bbcfe2834f71fa821e1cb113a723f">XPuf_ClearPufID()</a>.</p>

</div>
</div>
<h2 class="groupheader">Function Documentation</h2>
<a class="anchor" id="ga651bbcfe2834f71fa821e1cb113a723f"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">int XPuf_ClearPufID </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>This function clears PUF ID. </p>
<dl class="section return"><dt>Returns</dt><dd><ul>
<li>XST_SUCCESS if PUF ID is cleared successfully</li>
<li>XPUF_ERROR_PUF_ID_ZERO_TIMEOUT if time out while clearing PUF ID </li>
</ul>
</dd></dl>
<p>Set least significant bit in the PUF_CLEAR register.</p>
<p>The API waits for ID_ZERO bit to be set in PUF Status register. If ID zero bit is not set within 1 second then returns XPUF_ERROR_PUF_ID_ZERO_TIMEOUT else returns XST_SUCCESS.</p>

<p>References <a class="el" href="group__xpuf__apis.html#ga8eda4f7307742eae0ea34465e43d2555">XPUF_STATUS_WAIT_TIMEOUT</a>.</p>

</div>
</div>
<a class="anchor" id="ga03c85715b04394967ebb2274f09f510a"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">int XPuf_GenerateFuseFormat </td>
          <td>(</td>
          <td class="paramtype">XPuf_Data *&#160;</td>
          <td class="paramname"><em>PufData</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Converts the PUF Syndrome data to eFUSE writing format. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">PufData</td><td>Pointer to XPuf_Data structure which includes options to configure PUF.</td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><ul>
<li>XST_SUCCESS Syndrome data is successfully trimmed</li>
<li>XPUF_ERROR_INVALID_PARAM PufData instance pointer is NULL</li>
</ul>
</dd></dl>
<dl class="section note"><dt>Note</dt><dd>Formatted data will be available at PufData-&gt;EfuseSynData </dd></dl>
<p>Check if PufData instance pointer is NULL. If NULL, return XPUF_ERROR_INVALID_PARAM.</p>
<p>Copy syndrome data from instance pointer to a local variable.</p>
<p>Trimming logic for PUF Syndrome Data:</p>
<p>Space allocated in eFUSE for syndrome data = 4060bits</p>
<p>eFUSE02 - 2032bits</p>
<p>eFUSE03 - 2028bits</p>
<p>PUF Helper data generated for 4K Mode through registration is 140 Words = 140*32 = 4480 bits. Remove lower 12 bits of every fourth word of syndrome data.</p>
<p>After removing these bits remaining syndrome data will be exactly 4060bits which will fit into eFUSE.</p>
<h2>Illustration: </h2>
<p>454D025B</p>
<p>CDCB36FC</p>
<p>EE1FE4C5</p>
<p>3FE53F74 &ndash;&gt; F74 has to removed &amp; next word upper 12 bits have to be shifted here</p>
<p>3A0AE7F8</p>
<p>2373F03A</p>
<p>C83188AF</p>
<p>3A5EB687&ndash;&gt; 687 has to be removed</p>
<p>B83E4A1D</p>
<p>D53B5C50</p>
<p>FA8B33D9</p>
<p>07EEFF43 &ndash;&gt; F43 has to be removed</p>
<p>CD01973F</p>
<p>........</p>
<p>........</p>
<p>........</p>
<p>Use the above mentioned logic to trim the data and copy the trimmed data in EfuseSynData array in the instance pointer and return XST_SUCCESS.</p>

</div>
</div>
<a class="anchor" id="ga2f60c4624b046d3f5c74d8cb01f8f90d"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">int XPuf_Regeneration </td>
          <td>(</td>
          <td class="paramtype">XPuf_Data *&#160;</td>
          <td class="paramname"><em>PufData</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>This function regenerates PUF data using helper data stored in eFUSE or external memory. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">PufData</td><td>Pointer to XPuf_Data structure which includes options to configure PUF.</td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><ul>
<li>XST_SUCCESS on successful PUF Regeneration</li>
<li>XPUF_ERROR_INVALID_PARAM if PufData is NULL</li>
<li>XPUF_ERROR_INVALID_REGENERATION_TYPE if selected regeneration type is invalid</li>
<li>XPUF_ERROR_CHASH_NOT_PROGRAMMED Helper data not provided</li>
<li>XPUF_ERROR_PUF_STATUS_DONE_TIMEOUT Timeout occurred while waiting for PUF done bit</li>
<li>XPUF_ERROR_PUF_DONE_KEY_NT_RDY Key ready bit and ID ready bit is not set</li>
<li>XPUF_ERROR_PUF_DONE_ID_NT_RDY Id ready bit is not set</li>
<li>XPUF_IRO_FREQ_WRITE_MISMATCH Mismatch in writing or reading IRO frequency at the time of PUF regeneration</li>
<li>XST_FAILURE Unexpected event</li>
</ul>
</dd></dl>
<dl class="section note"><dt>Note</dt><dd>PUF is only supported when using a nominal VCC_PMC of 0.70V and IRO frequency of 320 MHz </dd></dl>
<p>Perform input parameters validation, return XPUF_ERROR_INVALID_PARAM if input parameters are invalid.</p>
<p>Check if requested PUF operation is not PUF on demand regeneration or ID only regeneration. If yes, return XPUF_ERROR_INVALID_PARAM.</p>
<p>Check that MSB of PUF shutter value is in sync with Global variation filter option. In case of mismatch, return XPUF_SHUTTER_GVF_MISMATCH.</p>
<p>When registering the PUF, the PMC internal ring oscillator (IRO) frequency must be set to 320 MHz. When the Versal ACAP boots, it always uses the default frequency of 320 MHz for -LP devices and 400 MHz for -MP,-HP devices. If the IRO frequency at boot does not match the IRO frequency during registration, there is a potential of reduced stability which can impact the PUFs ability to regenerate properly.</p>
<p>Validate the access rules for PUF regeneration. If PUF_DIS or PUF_REGEN_DIS eFuse bits are set, then return XPUF_ERROR_REGENERATION_INVALID. If read from eFuse cache is selected and PUF_HD_INVLD bit is set then return XPUF_ERROR_REGEN_PUF_HD_INVALID.</p>
<p>Update the helper data for PUF regeneration according to the location of helper data provided by the user.</p>
<p>Configures the Global Variation Filter option provided by user and updates PUF Configuration0 register.</p>
<p>Update PUF Configuration1 register as 4k Registration mode.</p>
<p>Update Shutter value in PUF_SHUT register.</p>
<p>Checks if SLVERR is enabled for PMC_GLOBAL, then disable the SLVERR for PMC_GLOBAL before regeneration starts and enables it again once PUF regeneration is done.</p>
<p>Update PUF Ring Oscillator Swap setting for Versal Net device, do nothing in case of Versal.</p>
<p>If On demand regeneration is selected by user then trigger PUF_CMD for PUF On Demand regeneration. If ID only regeneration is selected then trigger PUF_CMD for PUF ID only regeneration. If invalid input, return XPUF_ERROR_INVALID_REGENERATION_TYPE.</p>
<p>Enabling the SLVERR after regeneration, if SLVERR is enabled previously in PMC_GLOBAL.</p>
<p>If IRO frequency is updated to 320MHz then set frequency back to 400MHz and if the frequency is not set then return XPUF_IRO_FREQ_WRITE_MISMATCH else, Return status.</p>

<p>References <a class="el" href="xpuf__defs_8h.html#a9382543db8550e50f67432edcab2413e">XPUF_REGEN_ID_ONLY</a>, and <a class="el" href="xpuf__defs_8h.html#aa9fd28d7474a740dad170102dd6e8d8f">XPUF_REGEN_ON_DEMAND</a>.</p>

</div>
</div>
<a class="anchor" id="gae2607f20a8f0199c8f0eb53d0dfc9f0a"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">int XPuf_Registration </td>
          <td>(</td>
          <td class="paramtype">XPuf_Data *&#160;</td>
          <td class="paramname"><em>PufData</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>This functions performs PUF registration. </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">PufData</td><td>Pointer to XPuf_Data structure which includes options to configure PUF.</td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><ul>
<li>XST_SUCCESS PUF registration successful</li>
<li>XPUF_ERROR_INVALID_PARAM PufData is NULL</li>
<li>XPUF_ERROR_SYNDROME_WORD_WAIT_TIMEOUT Timeout occurred while waiting for PUF Syndrome data</li>
<li>XPUF_ERROR_PUF_DONE_WAIT_TIMEOUT Timeout occurred while waiting for PUF done bit at the time of PUF registration</li>
<li>XPUF_IRO_FREQ_WRITE_MISMATCH Mismatch in writing or reading IRO frequency</li>
<li>XST_FAILURE Unexpected event</li>
</ul>
</dd></dl>
<dl class="section note"><dt>Note</dt><dd>Helper data will be available in PufData-&gt;SyndromeData, PufData-&gt;Chash, PufData-&gt;Aux. PUF is only supported when using a nominal VCC_PMC of 0.70V and IRO frequency of 320 MHz </dd></dl>
<p>Perform input parameters validation, return XPUF_ERROR_INVALID_PARAM if input parameters are invalid.</p>
<p>Check that MSB of PUF shutter value is in sync with Global variation filter option. In case of mismatch, return XPUF_SHUTTER_GVF_MISMATCH.</p>
<p>When registering the PUF, the PMC internal ring oscillator (IRO) frequency must be set to 320 MHz. When the Versal ACAP boots, it always uses the default frequency of 320 MHz for -LP devices and 400 MHz for -MP,-HP devices. If the IRO frequency at boot does not match the IRO frequency during registration, there is a potential of reduced stability which can impact the PUFs ability to regenerate properly.</p>
<p>Validate if secure control bits for each PUF operations are set or not.</p>
<p>Check GlobalVariationFilter user option. If TRUE then set GLBL_FILTER and HASH_SEL bits else, set only HASH_SEL bit in in PUF_CFG0 register.</p>
<p>Update PUF Configuration1 register as 4k Registration mode.</p>
<p>Update shutter value for PUF registration.</p>
<p>Update PUF Ring Oscillator Swap setting for Versal Net device, do nothing in case of Versal.</p>
<p>Trigger PUF registration.</p>
<p>PUF helper data includes Syndrome data, CHash and Auxiliary data. Capturing Syndrome data word by word.</p>
<p>Once complete Syndrome data is captured and PUF operation is done, read CHash, Auxiliary data and PUF ID.</p>
<p>If IRO frequency is updated to 320MHz then set frequency back to 400MHz and if the frequency is not set then return XPUF_IRO_FREQ_WRITE_MISMATCH. else, return Status.</p>

<p>References <a class="el" href="group__xpuf__apis.html#ga4d7d5a3b73fb92f6f65e2a2205b74195">XPUF_AUX_MASK_VALUE</a>, <a class="el" href="group__xpuf__server__apis.html#ga4ab1beae9987b6ab994e4cf06c77dc1a">XPUF_AUX_SHIFT_VALUE</a>, <a class="el" href="group__xpuf__apis.html#ga5a9afe10c38f97cc7f9793a02463c131">XPUF_OV_MASK_VALUE</a>, <a class="el" href="group__xpuf__apis.html#gad16dd5805786cdbf430a04e61c961185">XPUF_PMC_GLOBAL_PUF_ID_CAPTURE</a>, and <a class="el" href="group__xpuf__apis.html#ga195a89fe38d4e810f356aeb626bfb964">XPUF_PMC_GLOBAL_PUF_KEY_CAPTURE</a>.</p>

</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
	<p class="footer">&copy; Copyright 2015-2022 Xilinx, Inc. All Rights Reserved.</p>
	<p class="footer">&copy; Copyright 2022-2023 Advanced Micro Devices, Inc. All Rights Reserved.</p>
</div>
</body>
</html>
